home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kstreamsocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-09-10  |  7.8 KB  |  250 lines
  1. /*  -*- C++ -*-
  2.  *  Copyright (C) 2003 Thiago Macieira <thiago@kde.org>
  3.  *
  4.  *
  5.  *  Permission is hereby granted, free of charge, to any person obtaining
  6.  *  a copy of this software and associated documentation files (the
  7.  *  "Software"), to deal in the Software without restriction, including
  8.  *  without limitation the rights to use, copy, modify, merge, publish,
  9.  *  distribute, sublicense, and/or sell copies of the Software, and to
  10.  *  permit persons to whom the Software is furnished to do so, subject to
  11.  *  the following conditions:
  12.  *
  13.  *  The above copyright notice and this permission notice shall be included 
  14.  *  in all copies or substantial portions of the Software.
  15.  *
  16.  *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17.  *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18.  *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19.  *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20.  *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21.  *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22.  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23.  */
  24.  
  25. #ifndef KSTREAMSOCKET_H
  26. #define KSTREAMSOCKET_H
  27.  
  28. #include <qstring.h>
  29.  
  30. #include "kclientsocketbase.h"
  31.  
  32. /** A namespace to store all networking-related (socket) classes. */
  33. namespace KNetwork {
  34.  
  35. class KResolverEntry;
  36. class KResolverResults;
  37. class KServerSocket;
  38. class KBufferedSocket;
  39.  
  40. class KStreamSocketPrivate;
  41. /** @class KStreamSocket kstreamsocket.h kstreamsocket.h
  42.  *  @brief Simple stream socket
  43.  *
  44.  * This class provides functionality to creating unbuffered, stream
  45.  * sockets. In the case of Internet (IP) sockets, this class creates and
  46.  * uses TCP/IP sockets.
  47.  *
  48.  * Objects of this class start, by default, on non-blocking mode. Call
  49.  * setBlocking if you wish to change that.
  50.  *
  51.  * KStreamSocket objects are thread-safe and can be used in auxiliary
  52.  * threads (i.e., not the thread in which the Qt event loop runs in).
  53.  * Note that KBufferedSocket cannot be used reliably in an auxiliary thread.
  54.  *
  55.  * Sample usage:
  56.  * \code
  57.  *   QByteArray httpGet(const QString& hostname)
  58.  *   {
  59.  *     KStreamSocket socket(hostname, "http");
  60.  *     if (!socket.connect())
  61.  *       return QByteArray();
  62.  *     QByteArray data = socket.readAll();
  63.  *     return data;
  64.  *   }
  65.  * \endcode
  66.  *
  67.  * Here's another sample, showing asynchronous operation:
  68.  * \code
  69.  *  DataRetriever::DataRetriever(const QString& hostname, const QString& port)
  70.  *    : socket(hostname, port)
  71.  *  {
  72.  *    // connect signals to our slots
  73.  *    QObject::connect(&socket, SIGNAL(connected(const KResolverEntry&)),
  74.  *                     this, SLOT(slotSocketConnected()));
  75.  *    QObject::connect(&socket, SIGNAL(gotError(int)),
  76.  *                     this, SLOT(slotSocketError(int)));
  77.  *    QObject::connect(&socket, SIGNAL(readyRead()),
  78.  *                     this, SLOT(slotSocketReadyToRead()));
  79.  *    QObject::connect(&socket, SIGNAL(readyWrite()),
  80.  *                     this, SLOT(slotSocketReadyToWrite()));
  81.  *
  82.  *    // set non-blocking mode in order to work asynchronously
  83.  *    socket.setBlocking(false);
  84.  *
  85.  *    // turn on signal emission
  86.  *    socket.enableRead(true);
  87.  *    socket.enableWrite(true);
  88.  *
  89.  *    // start connecting
  90.  *    socket.connect();
  91.  *  }
  92.  * \endcode
  93.  *
  94.  * @see KNetwork::KBufferedSocket, KNetwork::KServerSocket
  95.  * @author Thiago Macieira <thiago@kde.org>
  96.  */
  97. class KDECORE_EXPORT KStreamSocket: public KClientSocketBase
  98. {
  99.   Q_OBJECT
  100.  
  101. public:
  102.   /**
  103.    * Default constructor.
  104.    *
  105.    * @param node    destination host
  106.    * @param service    destination service to connect to
  107.    * @param parent    the parent QObject object
  108.    * @param name        name for this object
  109.    */
  110.   KStreamSocket(const QString& node = QString::null, const QString& service = QString::null,
  111.         QObject* parent = 0L, const char *name = 0L);
  112.  
  113.   /**
  114.    * Destructor. This closes the socket.
  115.    */
  116.   virtual ~KStreamSocket();
  117.  
  118.   /**
  119.    * Retrieves the timeout value (in milliseconds).
  120.    */
  121.   int timeout() const;
  122.  
  123.   /**
  124.    * Retrieves the remaining timeout time (in milliseconds). This value
  125.    * equals @ref timeout() if there's no connection in progress.
  126.    */
  127.   int remainingTimeout() const;
  128.  
  129.   /**
  130.    * Sets the timeout value. Setting this value while a connection attempt
  131.    * is in progress will reset the timer.
  132.    *
  133.    * Please note that the timeout value is valid for the connection attempt
  134.    * only. No other operations are timed against this value -- including the
  135.    * name lookup associated.
  136.    *
  137.    * @param msecs        the timeout value in milliseconds
  138.    */
  139.   void setTimeout(int msecs);
  140.  
  141.   /**
  142.    * Binds this socket to the given nodename and service,
  143.    * or use the default ones if none are given. In order to bind to a service
  144.    * and allow the operating system to choose the interface, set @p node to
  145.    * QString::null.
  146.    * 
  147.    * Reimplemented from KClientSocketBase.
  148.    *
  149.    * Upon successful binding, the @ref bound signal will be
  150.    * emitted. If an error is found, the @ref gotError
  151.    * signal will be emitted.
  152.    *
  153.    * @note Due to the internals of the name lookup and binding
  154.    *       mechanism, some (if not most) implementations of this function
  155.    *       do not actually bind the socket until the connection
  156.    *       is requested (see @ref connect). They only set the values
  157.    *       for future reference.
  158.    *
  159.    * This function returns true on success.
  160.    *
  161.    * @param node    the nodename
  162.    * @param service    the service
  163.    */
  164.   virtual bool bind(const QString& node = QString::null,
  165.             const QString& service = QString::null);
  166.  
  167.   /**
  168.    * Reimplemented from KClientSocketBase. Connect this socket to this
  169.    * specific address.
  170.    *
  171.    * Unlike @ref bind(const QString&, const QString&) above, this function
  172.    * really does bind the socket. No lookup is performed. The @ref bound
  173.    * signal will be emitted.
  174.    */
  175.   virtual bool bind(const KResolverEntry& entry)
  176.   { return KClientSocketBase::bind(entry); }
  177.  
  178.   /**
  179.    * Reimplemented from KClientSocketBase.
  180.    *
  181.    * Attempts to connect to the these hostname and service,
  182.    * or use the default ones if none are given. If a connection attempt
  183.    * is already in progress, check on its state and set the error status
  184.    * (NoError, meaning the connection is completed, or InProgress).
  185.    *
  186.    * If the blocking mode for this object is on, this function will only
  187.    * return when all the resolved peer addresses have been tried or when
  188.    * a connection is established.
  189.    *
  190.    * Upon successfully connecting, the @ref connected signal 
  191.    * will be emitted. If an error is found, the @ref gotError
  192.    * signal will be emitted.
  193.    *
  194.    * This function also implements timeout handling.
  195.    *
  196.    * @param node    the remote node to connect to
  197.    * @param service    the service on the remote node to connect to
  198.    */
  199.   virtual bool connect(const QString& node = QString::null,
  200.                const QString& service = QString::null);
  201.  
  202.   /**
  203.    * Unshadowing from KClientSocketBase.
  204.    */
  205.   virtual bool connect(const KResolverEntry& entry);
  206.  
  207. signals:
  208.   /**
  209.    * This signal is emitted when a connection timeout occurs.
  210.    */
  211.   void timedOut();
  212.  
  213. private slots:
  214.   void hostFoundSlot();
  215.   void connectionEvent();
  216.   void timeoutSlot();
  217.  
  218. private:
  219.   /**
  220.    * @internal
  221.    * If the user requested local bind before connection, bind the socket to one
  222.    * suitable address and return true. Also sets d->local to the address used.
  223.    *
  224.    * Return false in case of error.
  225.    */
  226.   bool bindLocallyFor(const KResolverEntry& peer);
  227.  
  228.   /**
  229.    * @internal
  230.    * Finishes the connection process by setting internal values and
  231.    * emitting the proper signals.
  232.    *
  233.    * Note: assumes d->local iterator points to the address that we bound
  234.    * to.
  235.    */
  236.   void connectionSucceeded(const KResolverEntry& peer);
  237.  
  238.   KStreamSocket(const KStreamSocket&);
  239.   KStreamSocket& operator=(const KStreamSocket&);
  240.  
  241.   KStreamSocketPrivate *d;
  242.  
  243.   friend class KServerSocket;
  244.   friend class KBufferedSocket;
  245. };
  246.  
  247. }                 // namespace KNetwork
  248.  
  249. #endif
  250.